LIBTOOL

Section: User Commands (1)
Updated: July 19, 1993
Index Return to Main Contents

NAME

libtool - create libraries
ranlib - add or update the table of contents of archive libraries

SYNOPSIS

libtool -o output [ -sac ] [ - ] file...
ranlib [ -sact ] [ - ] archive...

DESCRIPTION

The libtool command takes the specified input object files and creates a library for use with the link editor, ld(1). The library's name is specified by output (the argument to the -o flag). The input object files may be in any correct format that contains object files (``fat'' files, archives, object files). Libtool will not put any non-object input file into the output library (unlike ranlib, which allows this in the archives it operates on).

Libtool is intended to replace ar(5) and ranlib. For backward compatibility, ranlib is still available, and it supports fat files.

Ranlib adds or updates the table of contents to each archive so it can be linked by the link editor, ld(1). The table of contents is a file at the beginning of the archive that indicates which symbols are defined in which library members. Because ranlib rewrites the archive, sufficient temporary file space must be available in the file system that contains the current directory. Ranlib takes all correct forms of libraries (fat files containing archives, and simple archives) and updates the table of contents for all archives in the file. Ranlib also takes one common incorrect form of archive, an archive whose members are fat object files, adding or updating the table of contents and producing the library in correct form (a fat file containing multiple archives).

The name for a table of contents begins with ``__.SYMDEF''. Currently, there are two types of table of contents produced by libtool and ranlib and understood by the link editor, ld(1). These are explained below, under the -s and -a options.

When producing a fat file from objects of the same CPU type and differing CPU subtypes, libtool and ranlib create at most one library for each CPU type, rather than a separate library in a fat file for each of the unique pairings of CPU type and CPU subtype. Thus, the resulting CPU subtype for each library is the _ALL CPU subtype for that CPU type. This strategy strongly encourages the implementor of a library to create one library that chooses optimum code to run at run time, rather than at link time.

OPTIONS

The following options pertain to the table of contents, and apply to both libtool and ranlib:
-s: Produce the preferred type of table of contents, which results in faster link editing when linking with the archive. The order of the table of contents is sorted by symbol name. The library member name of this type of table of contents is ``__.SYMDEF SORTED''. This type of table of contents can only be produced when the library does not have multiple members that define the same symbol. This is the default.
-a: Produce the original type of table of contents, whose order is based on the order of the members in the archive. The library member name of this type of table of contents is ``__.SYMDEF''. This type of table of contents must be used when the library has multiple members that define the same symbol.
-c: Include common symbols as definitions with respect to the table of contents. This is seldom the intended behavior for linking from a library, as it forces the linking of a library member just because it uses an uninitialized global that is undefined at that point in the linking. This option is included only because this was the original behavior of ranlib. This option is not the default.

For compatibility, the following ranlib option is accepted (but ignored):

-t: This option used to request that ranlib only ``touch'' the archives instead of modifying them. The option is now ignored, and the table of contents is rebuilt.

One other option applies to both libtool and ranlib:

-: Treat all remaining arguments as names of files (or archives) and not as options.

BUGS

The way libraries used to be created, errors were possible if the library was modified with ar(1) and the table of contents was not updated by rerunning ranlib(1). Thus the link editor, ld, warns when the modification date of a library is more recent than the creation date of its table of contents. Unfortunately, this means that you get the warning even if you only copy the library.

This document was created by man2html, using the manual pages.
Time: 17:20:33 GMT, March 25, 2025